<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<body>
<head>
<title>SRFI 74: Octet-Addressed Binary Blocks</title>
</head>

<body>
<H1>Title</H1>

Octet-Addressed Binary Blocks

<H1>Authors</H1>

Michael Sperber

<p>
This SRFI is currently in ``final'' status. To see an explanation of each
status that a SRFI can hold, see
<a HREF="http://srfi.schemers.org/srfi-process.html">here</a>.
To
provide input on this SRFI, please <code>
<a HREF="mailto:srfi-74@srfi.schemers.org">mailto:srfi-74@srfi.schemers.org</a></code>.
See <a HREF="http://srfi.schemers.org/srfi-list-subscribe.html">instructions
here</a> to subscribe to the list. You can access previous messages via
<a HREF="http://srfi.schemers.org/srfi-74/mail-archive/maillist.html">the
archive of the mailing list</a>.

</p>
<ul>
  <li>Received: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-74/srfi-74.html?rev=1.1">2005/07/06</a></li>
  <li>Draft: 2005/07/06 - 2005/09/04</li>
  <li>Revised: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-74/srfi-74.html?rev=1.2">2005/07/22</a>
  <li>Revised: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-74/srfi-74.html?rev=1.3">2005/12/04</a>
  <li>Final: <a href="http://srfi.schemers.org/cgi-bin/viewcvs.cgi/*checkout*/srfi/srfi-74/srfi-74.html?rev=1.4">2005/12/15</a>
</ul>
<h1>Abstract</h1><p>This SRFI defines a set of procedures for creating, accessing, and manipulating octet-addressed blocks of binary data, in short, <i>blobs</i>. The SRFI provides access primitives for fixed-length integers of arbitrary size, with specified endianness, and a choice of unsigned and two's complement representations.</p><h1>Rationale</h1><p>Many applications must deal with blocks of binary data by accessing them in various ways---extracting signed or unsigned numbers of various sizes.  Such an application can use octet vectors as in <a href="http://srfi.schemers.org/srfi-66/">SRFI 66</a> or any of the other types of homogeneous vectors in <a href="http://srfi.schemers.org/srfi-4/">SRFI 4</a>, but these both only allow retrieving the binary data of one type.</p><p>This is awkward in many situations, because an application might access different kinds of entities from a single binary block.  Even for uniform blocks, the disjointness of the various vector data types in SRFI 4 means that, say, an I/O API needs to provide an army of procedures for each of them in order to provide efficient access to binary data.</p><p>Therefore, this SRFI provides a <em>single</em> type for blocks of binary data with multiple ways to access that data.  It deals only with integers in various sizes with specified endianness, because these are the most frequent applications.  Dealing with other kinds of binary data, such as floating-point numbers or variable-size integers would be natural extensions, but are left for a future SRFI.</p><h1>Specification</h1><h2>General remarks</h2><p>Blobs are objects of a new type.  Conceptually, a blob represents a sequence of octets.</p><p>Scheme systems implementing both SRFI 4 and/or SRFI 66 and this SRFI may or may not use the same type for u8vector and blobs.  They are encouraged to do so, however.</p><p>As with u8vectors, the length of a blob is the number of octets it contains.  This number is fixed.  A valid index into a blob  is an exact, non-negative integer.  The first octet of a blob  has index 0, the last octet has an index one less than the  length of the blob.</p><p>Generally, the access procedures come in different flavors according to the size of the represented integer, and the <a href="http://en.wikipedia.org/wiki/Endianness">endianness</a> of the representation.  The procedures also distinguish signed and unsigned representations.  The signed representations all use <a href="http://en.wikipedia.org/wiki/Two's_complement">two's complement</a>.</p><p>For procedures that have no "natural" return value, this SRFI often uses the sentence</p><p><em>The return values are unspecified.</em></p><p>This means that number of return values  and the return values are unspecified.  However, the number of return values  is such that it is accepted by a continuation created by <code>begin</code>.  Specifically, on Scheme implementations where continuations created by <code>begin</code> accept an arbitrary number of arguments (this includes most implementations), it is suggested that the procedure return zero return values.</p><h2>Interface</h2><dl><dt><code>(endianness </code><code>big</code><code>)</code> (syntax)</dt><dt><code>(endianness </code><code>little</code><code>)</code> (syntax)</dt><dt><code>(endianness </code><code>native</code><code>)</code> (syntax)</dt><dd><p><code>(endianness big)</code> and <code>(endianness little)</code> evaluate to two distinct and unique objects representing an  endianness.  The <code>native</code> endianness evaluates to the endianness of the underlying machine architecture, and must be <code>eq?</code> to either <code>(endianness big)</code> or <code>(endianness little)</code>.</p></dd><dt><code>(blob? </code><var>obj</var><code>)</code></dt><dd><p>Returns <code>#t</code> if <var>obj</var> is a blob, otherwise returns <code>#f</code>.</p></dd><dt><code>(make-blob </code><var>k</var><code>)</code></dt><dd><p>Returns a newly allocated blob of <var>k</var> octets, all of them 0.</p></dd><dt><code>(blob-length </code><var>blob</var><code>)</code></dt><dd><p>Returns the number of octets in <var>blob</var> as an exact integer.</p></dd><dt><code>(blob-u8-ref </code><var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-s8-ref </code><var>blob</var> <var>k</var><code>)</code></dt><dd><p><var>K</var> must be a valid index of <var>blob</var>.</p><p><code>Blob-u8-ref</code> returns the octet at index <var>k</var> of <var>blob</var>.</p><p><code>Blob-s8-ref</code> returns the exact integer corresponding to the two's complement representation at index <var>k</var> of <var>blob</var>.</p></dd><dt><code>(blob-u8-set! </code><var>blob</var> <var>k</var> <var>octet</var><code>)</code></dt><dt><code>(blob-s8-set! </code><var>blob</var> <var>k</var> <var>byte</var><code>)</code></dt><dd><p><var>K</var> must be a valid index of <var>blob</var>.</p><p><code>Blob-u8-set!</code> stores <var>octet</var> in element <var>k</var> of <var>blob</var>.</p><p><var>Byte</var>, must be an exact integer in the interval {-128, ..., 127}. <code>Blob-u8-set!</code> stores the two's complement representation  of <var>byte</var> in element <var>k</var> of <var>blob</var>.</p><p>The return values are unspecified.</p></dd><dt><code>(blob-uint-ref </code><var>size</var> <var>endianness</var> <var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-sint-ref </code><var>size</var> <var>endianness</var> <var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-uint-set! </code><var>size</var> <var>endianness</var> <var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-sint-set! </code><var>size</var> <var>endianness</var> <var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dd><p><var>Size</var> must be a positive exact integer. <var>K</var> must be a valid index of <var>blob</var>; so must the indices {<var>k</var>, ..., <var>k</var> + <var>size</var> - 1}. <var>Endianness</var> must be an endianness object. </p><p><code>Blob-uint-ref</code> retrieves the exact integer corresponding to the unsigned representation of size <var>size</var> and specified by <var>endianness</var> at indices {<var>k</var>, ..., <var>k</var> + <var>size</var> - 1}.</p><p><code>Blob-sint-ref</code> retrieves the exact integer corresponding to the two's complement representation of size <var>size</var> and specified by <var>endianness</var> at indices {<var>k</var>, ..., <var>k</var> + <var>size</var> - 1}.</p><p>For <code>blob-uint-set!</code>, <var>n</var> must be an exact integer in the interval [0, (256^<var>size</var>)-1]. <code>Blob-uint-set!</code> stores the unsigned representation of size <var>size</var> and specified by <var>endianness</var> into the blob at indices {<var>k</var>, ..., <var>k</var> + <var>size</var> - 1}.</p><p>For <code>blob-uint-set!</code>, <var>n</var> must be an exact integer in the interval [-256^(<var>size</var>-1), (256^(<var>size</var>-1))-1]. <code>Blob-sint-set!</code> stores the two's complement representation of size <var>size</var> and specified by <var>endianness</var> into the blob at indices {<var>k</var>, ..., <var>k</var> + <var>size</var> - 1}.</p></dd><dt><code>(blob-u16-ref </code><var>endianness</var> <var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-s16-ref </code><var>endianness</var> <var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-u16-native-ref </code><var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-s16-native-ref </code><var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-u16-set! </code><var>endianness</var> <var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-s16-set! </code><var>endianness</var> <var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-u16-native-set! </code><var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-s16-native-set! </code><var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dd><p><var>K</var> must be a valid index of <var>blob</var>; so must the index <var>k</var>+ 1. <var>Endianness</var> must be an endianness object. </p><p>These retrieve and set two-octet representations of numbers at indices <var>k</var> and <var>k</var>+1, according to the endianness specified by <var>endianness</var>. The procedures with <code>u16</code> in their names deal with the unsigned representation, those with <code>s16</code> with the two's complement representation.</p><p>The procedures with <code>native</code> in their names employ the native endianness, and only work at aligned indices: <var>k</var> must be a multiple of 2.  It is an error to use them at non-aligned indices.</p></dd><dt><code>(blob-u32-ref </code><var>endianness</var> <var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-s32-ref </code><var>endianness</var> <var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-u32-native-ref </code><var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-s32-native-ref </code><var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-u32-set! </code><var>endianness</var> <var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-s32-set! </code><var>endianness</var> <var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-u32-native-set! </code><var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-s32-native-set! </code><var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dd><p><var>K</var> must be a valid index of <var>blob</var>; so must the indices {<var>k</var>, ..., <var>k</var>+ 3}. <var>Endianness</var> must be an endianness object. </p><p>These retrieve and set four-octet representations of numbers at indices {<var>k</var>, ..., <var>k</var>+ 3}, according to the endianness specified by <var>endianness</var>. The procedures with <code>u32</code> in their names deal with the unsigned representation, those with <code>s32</code> with the two's complement representation.</p><p>The procedures with <code>native</code> in their names employ the native endianness, and only work at aligned indices: <var>k</var> must be a multiple of 4.  It is an error to use them at non-aligned indices.</p></dd><dt><code>(blob-u64-ref </code><var>endianness</var> <var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-s64-ref </code><var>endianness</var> <var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-u64-native-ref </code><var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-s64-native-ref </code><var>blob</var> <var>k</var><code>)</code></dt><dt><code>(blob-u64-set! </code><var>endianness</var> <var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-s64-set! </code><var>endianness</var> <var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-u64-native-set! </code><var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dt><code>(blob-s64-native-set! </code><var>blob</var> <var>k</var> <var>n</var><code>)</code></dt><dd><p><var>K</var> must be a valid index of <var>blob</var>; so must the indices {<var>k</var>, ..., <var>k</var>+ 7}. <var>Endianness</var> must be an endianness object. </p><p>These retrieve and set eight-octet representations of numbers at indices {<var>k</var>, ..., <var>k</var>+ 7}, according to the endianness specified by <var>endianness</var>. The procedures with <code>u64</code> in their names deal with the unsigned representation, those with <code>s64</code> with the two's complement representation.</p><p>The procedures with <code>native</code> in their names employ the native endianness, and only work at aligned indices: <var>k</var> must be a multiple of 8.  It is an error to use them at non-aligned indices.</p></dd><dt><code>(blob=? </code><var>blob-1</var> <var>blob-2</var><code>)</code></dt><dd><p>Returns <var>#t</var> if <var>blob-1</var> and <var>blob-2</var> are equal---that is, if they have the same length and equal octets at all valid indices.</p></dd><dt><code>(blob-copy! </code><var>source</var> <var>source-start</var> <var>target</var> <var>target-start</var> <var>n</var><code>)</code></dt><dd><p>Copies data from blob <var>source</var> to blob <var>target</var>.  <var>Source-start</var>, <var>target-start</var>, and <var>n</var> must be non-negative exact integers that satisfy</p><p>0 &lt;= <var>source-start</var> &lt;= <var>source-start</var> + <var>n</var> &lt;= <code>(blob-length <var>source</var>)</code></p><p>0 &lt;= <var>target-start</var> &lt;= <var>target-start</var> + <var>n</var> &lt;= <code>(blob-length <var>target</var>)</code></p><p>This copies the octets from <var>source</var> at indices [<var>source-start</var>, <var>source-start</var> + <var>n</var>) to consecutive indices in <var>target</var> starting at <var>target-index</var>.</p><p>This must work even if the memory regions for the source and the target overlap, i.e., the octets at the target location after the copy must be equal to the octets at the source location before the copy.</p><p>The return values are unspecified.</p></dd><dt><code>(blob-copy </code><var>blob</var><code>)</code></dt><dd><p>Returns a newly allocated copy of blob <var>blob</var>.</p></dd><dt><code>(blob-&gt;u8-list </code><var>blob</var><code>)</code></dt><dt><code>(u8-list-&gt;blob </code><var>blob</var><code>)</code></dt><dd><p><code>blob-&gt;u8-list</code>returns a newly allocated list of the octets of <var>blob</var> in the same order.</p></dd><dd><p><code>U8-list-&gt;blob</code> returns a newly allocated blob whose elements are the elements of list <var>octets</var>, which must all be octets, in the same order. Analogous to <code>list-&gt;vector</code>.</p></dd><dt><code>(blob-&gt;uint-list </code><var>size</var> <var>endianness</var> <var>blob</var><code>)</code></dt><dt><code>(blob-&gt;sint-list </code><var>size</var> <var>endianness</var> <var>blob</var><code>)</code></dt><dt><code>(uint-list-&gt;blob </code><var>size</var> <var>endianness</var> <var>list</var><code>)</code></dt><dt><code>(sint-list-&gt;blob </code><var>size</var> <var>endianness</var> <var>list</var><code>)</code></dt><dd><p><var>Size</var> must be a positive exact integer. <var>Endianness</var> must be an endianness object.</p><p>These convert between lists of integers and their consecutive representations according to <var>size</var> and <var>endianness</var> in blobs in the same way as <code>blob-&gt;u8-list</code>, <code>blob-&gt;s8-list</code>, <code> u8-list-&gt;blob</code>, and <code>s8-list-&gt;blob</code> do for one-octet representations.</p></dd></dl><h1>Reference Implementation</h1><p>This <a href="blob.scm">reference implementation</a> makes use of <a href="http://srfi.schemers.org/srfi-23/">SRFI 23</a> (Error reporting mechanism), <a href="http://srfi.schemers.org/srfi-26/">SRFI 26</a> (Notation for Specializing Parameters without Currying), <a href="http://srfi.schemers.org/srfi-60/">SRFI 60</a> (Integers as Bits), and <a href="http://srfi.schemers.org/srfi-66">SRFI 66</a> (Octet Vectors) .</p><h1>Examples</h1><p>The <a href="example.scm">test suite</a> doubles as a source of examples.</p><h1>References</h1><ul><li><a href="http://srfi.schemers.org/srfi-4/">SRFI 4</a> (Homogeneous numeric vector datatypes)</li><li><a href="http://srfi.schemers.org/srfi-56/">SRFI 56</a> (Binary I/O)</li><li><a href="http://srfi.schemers.org/srfi-66/">SRFI 66</a> (Octet Vectors)</li></ul></body><H1>Copyright</H1>
Copyright (C) Michael Sperber (2005). All Rights Reserved. 
<p>
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
<p>
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
<p>
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

    <hr>
    <address>Editor: <a href="mailto:srfi-editors@srfi.schemers.org">David Van Horn</a></address>
</body></html>
